home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #2 / Monster Media No. 2 (Monster Media)(1994).ISO / prog_c / lzw4w10.zip / LZW4W.DOC < prev    next >
Text File  |  1994-07-12  |  37KB  |  961 lines

  1.  
  2.  
  3.                           LZW Data Compression Library
  4.  
  5.                                For Windows (C/C++)
  6.  
  7.  
  8.                                     (LZW4W)
  9.  
  10.  
  11.  
  12.                                  USERS MANUAL
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                                   Version 1.0
  19.  
  20.                                   July 11, 1994
  21.  
  22.  
  23.  
  24.  
  25.                         This software is provided as-is.
  26.                  There are no warranties, expressed or implied.
  27.  
  28.  
  29.  
  30.  
  31.                               Copyright (C) 1994
  32.                               All rights reserved
  33.  
  34.  
  35.  
  36.                               MarshallSoft Computing, Inc.
  37.                               Post Office Box 4543
  38.                               Huntsville AL 35815
  39.  
  40.                               205-881-4630 Voice / FAX
  41.                               205-880-9748 Support BBS
  42.  
  43.  
  44.                                        _______
  45.                                   ____|__     |                (R)
  46.                                --|       |    |-------------------
  47.                                  |   ____|__  |  Association of
  48.                                  |  |       |_|  Shareware
  49.                                  |__|   o   |    Professionals
  50.                                -----|   |   |---------------------
  51.                                     |___|___|    MEMBER
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.         LZW4W Users Manual                                     Page 1
  61.                               C O N T E N T S
  62.  
  63.  
  64.  
  65.  
  66.  
  67.          Chapter                                                   Page
  68.  
  69.          1.0 Introduction..............................................3
  70.              1.1 Distribution Files....................................3
  71.              1.2 Compiling the Library.................................4
  72.              1.3 User Support..........................................4
  73.              1.4 ASP Ombudsman.........................................5
  74.              1.5 Installation..........................................5
  75.          2.0 The LZW Algorithm.........................................6
  76.              2.1 LZW Compression.......................................6
  77.              2.2 LZW Expansion.........................................7
  78.              2.3 LZW Implementation....................................7
  79.          3.0 Example Programs..........................................8
  80.              3.1 RUNLZW................................................8
  81.              3.2 ARCHIVE...............................................9
  82.          4.0 Reader & Writer Functions................................10
  83.          5.0 Library Functions........................................11
  84.              5.1 InitLZW..............................................11
  85.              5.2 TermLZW..............................................11
  86.              5.3 Compress.............................................12
  87.              5.4 Expand...............................................12
  88.          6.0 Error Codes..............................................13
  89.              6.1 EXPANSION_ERROR......................................13
  90.              6.2 CANNOT_ALLOCATE......................................13
  91.              6.3 INTERNAL_ERROR.......................................13
  92.              6.4 NOT_READY............................................13
  93.              6.5 BAD_BITCODE..........................................13
  94.          7.0 Legal Issues.............................................14
  95.              7.1 Registration.........................................14
  96.              7.2 Referral Plan........................................14
  97.              7.3 License..............................................15
  98.              7.4 Warranty.............................................15
  99.          8.0 Revision History.........................................16
  100.          9.0 Other MarshallSoft Computing Products for Windows........16
  101.              9.1 The Personal Communications Library for Windows......16
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.         LZW4W Users Manual                                     Page 2
  121.          1.0 Introduction
  122.  
  123.  
  124.          LZW4W  consists  of a variable code size implementation of the LZW
  125.          (Lempel-Ziv-Welch) algorithm  for  compressing  and  decompressing
  126.          data.   LZW does particularly well on text files, achieving better
  127.          than a 50 % compression ratio for many files.
  128.  
  129.          The LZW algorithm is considered to be  one  of  the  best  general
  130.          purpose  algorithms  available  today.   The new high speed modems
  131.          that employ on-the-fly data compression (such as  MNP  5.0  &  the
  132.          V.42 bis international standard) use the LZW algorithm, as well as
  133.          such well known utility programs such as PKZIP.
  134.  
  135.          The  LZW4W  library  is  designed  to be used in a wide variety of
  136.          situations. Some of the possible uses include:
  137.  
  138.          1) Compression and expanding files on disk.
  139.          2) Compressing files "on the fly" before  sending  over  a  modem,
  140.             and then expanding on the receiving end.
  141.          3) Compression of data files used by your application program such
  142.             as help files, graphics screens, etc. The compressed data files
  143.             are then expanded as they are loaded by the application.
  144.  
  145.  
  146.          1.1 Distribution Files
  147.  
  148.          The distribution files are as follows:
  149.  
  150.           1) LZW4W.LIB   -- Windows library.
  151.           2) LZW4W.DOC   -- This documentation file.
  152.           3) LZW4W.INV   -- Invoice file.
  153.           4) RUNLZW.C    -- Compress/Expand Windows example program.
  154.           5) ARCHIVE.C   -- File archiving Windows example program.
  155.           6) LZW4W.H     -- Library prototypes.
  156.           7) *._B_       -- Borland C makefiles.
  157.           8) *._M_       -- Microsoft C makefiles.
  158.           9) RW_IO.C     -- Reader/Writer I/O source file.
  159.          10) RW_IO.H     -- Prototypes for above.
  160.          11) DIR_IO.C    -- Directory I/O source file.
  161.          12) DIR_IO.H    -- Prototypes for above.
  162.          13) SAYERROR.C  -- Displays text error messages.
  163.          14) SAYERROR.H  -- Prototypes for above.
  164.          15) DATABOX.C   -- Dialog box which request text from user.
  165.          16) DATABOX.H   -- Prototypes for above.
  166.          17) DISPLAY.C   -- Handles window text display.
  167.          18) DISPLAY.H   -- Prototypes for above.
  168.          19) ABOUT.C     -- ABOUT dialog box.
  169.          20) ABOUT.H     -- Prototypes for above.
  170.  
  171.          Registered users also receive:
  172.  
  173.           1) LZW4W.ASM   -- SOURCE CODE for the LZW4W libraries.
  174.           2) LZW4W.MAK   -- Makefile to make LZW4W.LIB
  175.  
  176.  
  177.  
  178.  
  179.  
  180.         LZW4W Users Manual                                     Page 3
  181.          1.2 Compiling the Library
  182.  
  183.          The  example  windows  programs can be compiled using the provided
  184.          makefiles. To compile the  example  programs  using  Microsoft  C,
  185.          type (use NMAKE rather than MAKE):
  186.  
  187.               NMAKE ARCHIVE._M_
  188.  
  189.               NMAKE RUNLZW._M_
  190.  
  191.          To compile the example programs using Borland C, type:
  192.  
  193.               MAKE -fARCHIVE._B_
  194.  
  195.               MAKE -fRUNLZW._B_
  196.  
  197.          The registered user can re-compile the source code (source code is
  198.          provided in the registered version only) for the library using the
  199.          provided  makefile  LZW4W.MAK,  or  the  library  can  be compiled
  200.          directly by:
  201.  
  202.               masm -Mx lzw4wlib.asm,lzw4wlib.obj;
  203.               del lzw4w.lib
  204.               lib lzw4w.lib+lzw4wlib.obj,lzw4w.map
  205.  
  206.  
  207.          1.3 User Support
  208.  
  209.          We  want you to be successful in developing your application using
  210.          our libraries! We depend on our customers to let us know what they
  211.          need in a library.  This means we are committed to  providing  the
  212.          best  libraries  that  we  can.   If  you  have any suggestions or
  213.          comments, please write to us or give us a call.
  214.  
  215.          If  you  are having a problem using LZW4W or any of our libraries,
  216.          call (205) 881-4630 between 1:30 PM and 9:30 PM CST Monday through
  217.          Saturday can call at other times and leave  a  message,  and  call
  218.          back  later during our regular business hours for a reply. You can
  219.          also FAX us at this same number at any time.
  220.  
  221.          You  may  also  call our 24 hour BBS (2400 baud, no parity, 8 data
  222.          bits, 1 stop bit) at any time.  The BBS will  contain  the  latest
  223.          shareware version of LZW4W, messages, and other related files. All
  224.          files  are  in standard ZIP format. You can leave a message on the
  225.          BBS, and we will usually have a reply  ready  for  you  within  24
  226.          hours.   The dedicated telephone number is 205-880-9748.  Set your
  227.          modem for 1200 to 9600 baud, 8 data bits, no parity, one stop bit.
  228.  
  229.          The  MarshallSoft  Computing,  Inc.   newsletter  "Comm  Talk"  is
  230.          published quarterly.  It discusses various communications problems
  231.          and  solutions using PCL4C (the communications library) as well as
  232.          related information such as data compression  issues.   Registered
  233.          users  receive  a  one  year complimentary subscription when first
  234.          registering and for  each  update  purchased.   However,  overseas
  235.          customers  who  want  the  newsletter  must  pay  $5  for postage.
  236.          Additional one year subscriptions are $15 (plus $5 for postage for
  237.          overseas customers).
  238.  
  239.  
  240.         LZW4W Users Manual                                     Page 4
  241.          1.4 ASP Ombudsman
  242.  
  243.  
  244.          MarshallSoft  Computing,  Inc.  is  a member of the Association of
  245.          Shareware Professionals (ASP).  ASP wants to make  sure  that  the
  246.          shareware principle works for you.  If you are unable to resolve a
  247.          shareware-related  problem  with  an  ASP member by contacting the
  248.          member directly, ASP may be able to help. The  ASP  Ombudsman  can
  249.          help you resolve a dispute or problem with an ASP member, but does
  250.          not provide technical support for members' products.  Please write
  251.          to  the  ASP  Ombudsman  at  545  Grover  Road,  Muskegon,  MI USA
  252.          49442-9427, Fax 616-788-2765, or send  a  CompuServe  message  via
  253.          CompuServe Mail to ASP Ombudsman 70007,3536.
  254.  
  255.  
  256.          1.5 Installation
  257.  
  258.  
  259.          (1) The Microsoft C and Borland C Windows compilers are supported.
  260.          Before installation of LZW4W, your C compiler  should  already  be
  261.          installed  on your system and tested. If you are not familiar with
  262.          makefiles, refer to your compiler manual. If  you  are  using  the
  263.          interactive  environment for, be sure to compile with the provided
  264.          makefiles first to verify your installation.
  265.  
  266.          (2) Make a backup  copy  of  your  distribution  disk.   Put  your
  267.          original distribution disk in a safe place.
  268.  
  269.          (3)  Create  a  work  directory  on  your work disk (normally your
  270.          harddisk). For example, to create a work directory named LZW4W, we
  271.          first log onto the work disk and then type:
  272.  
  273.                                MKDIR LZW4W
  274.  
  275.          (4)  Copy  all the files from your backup copy of the distribution
  276.          disk to your work directory.  For example, to  copy  from  the  A:
  277.          drive to your work directory, we type:
  278.  
  279.                               CD LZW4W
  280.                               COPY A:*.*
  281.  
  282.          (5)   Compile   RUNLZW.C  and  ARCHIVE.C.  For  example,  to  make
  283.          ARCHIVE.EXE:
  284.  
  285.              a) Borland Turbo C: Type
  286.  
  287.                   MAKE -fARCHIVE._B_
  288.  
  289.              b) Microsoft C: Type
  290.  
  291.                   NMAKE COMPRESS._M_
  292.  
  293.                 Note the use of NMAKE rather than MAKE above.
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.         LZW4W Users Manual                                     Page 5
  301.          2.0 The LZW Algorithm
  302.  
  303.  
  304.          The following discussion of the LZW algorithm is meant to  provide
  305.          a  high  level  overview  of  LZW.  For those interested in a more
  306.          detailed explanation, several good books  are  available  on  data
  307.          compression.  Most  of  them  contain  a  section  on  generic LZW
  308.          compression.
  309.  
  310.          The original public research papers on  what  is  now  called  LZW
  311.          compression are:
  312.  
  313.              J. ZIV and A. Lempel,
  314.              "A Universal Algorithm for Sequential Data Compression",
  315.              IEEE Transactions on Information Theory, May 1977.
  316.  
  317.              Terry Welch,
  318.              "A Technique for High-Performance Data Compression",
  319.               Computer, June 1984.
  320.  
  321.          Many subsequent papers have been published dealing  with  the  LZW
  322.          compression algorithm.
  323.  
  324.  
  325.          2.1 LZW Compression
  326.  
  327.  
  328.          The  LZW  compressor  reads  8-bit  bytes  from  a data source and
  329.          outputs N-bit codes each of which identifies a previously  defined
  330.          string.   The  value  of  N starts at 9. Thus, codes 0 through 255
  331.          (0xff) correspond with the standard character set, while codes 256
  332.          (0x100) through 511 (0x1ff) correspond to a byte-byte  pair  or  a
  333.          code-byte pair in the code table. After code 511 is output, 10 bit
  334.          codes  are used. This is repeated until the maximum number of bits
  335.          per code is reached. LZW4W can use a maximum value of 12, 13 or 14
  336.          bits per code. The recommended value is 14.
  337.  
  338.          The LZW compressor builds a code table as it compresses data.  The
  339.          code table consists of previously encountered strings.
  340.  
  341.          The basic LZW compression algorithm is as follows:
  342.  
  343.              STRING = get first input byte
  344.              while there is more input data
  345.                {BYTE = get next input byte
  346.                 if STRING+BYTE is in code table
  347.                    STRING=STRING+BYTE
  348.                 else
  349.                   {output code for STRING
  350.                    add STRING+BYTE to code table
  351.                    STRING = BYTE
  352.                   }
  353.               }
  354.              output the code for STRING
  355.  
  356.  
  357.  
  358.  
  359.  
  360.         LZW4W Users Manual                                     Page 6
  361.          2.2 LZW Expansion
  362.  
  363.  
  364.          The LZW expansion routine reads the N-bit codes previously created
  365.          by  the  LZW  compressor  and  reconstructs  the  code  table  (as
  366.          previously constructed by the compressor) as it is outputing 8-bit
  367.          bytes.  A code corresponds to a single byte (the first  256  codes
  368.          from 0x00 through 0xff), or a byte-byte pair in the code table, or
  369.          a  code-byte  pair  in the code table. In the later case, the code
  370.          part of the code-byte pair refers to another defined code pair  in
  371.          the  table.   As  each  code is read in, it is located in the code
  372.          table and the corresponding 8-bit bytes are  output.   This  means
  373.          that  codes  must be defined before they are needed for expansion.
  374.          Unlike  older  dictionary  based  compression  schemes,  the  code
  375.          dictionary  produced by the compressor routine does not have to be
  376.          provided to the expansion routine.
  377.  
  378.          The basic LZW de-compression algorithm is as follows:
  379.  
  380.              OLDCODE = input first code
  381.              output OLDCODE
  382.              while there is more input data
  383.                {NEWCODE = get next input code
  384.                 STRING = translation of NEWCODE
  385.                 output STRING
  386.                 BYTE = 1st byte of STRING
  387.                 add OLDCODE+BYTE to the code table
  388.                 OLDCODE = NEWCODE
  389.                }
  390.  
  391.  
  392.          2.3 Implementation
  393.  
  394.  
  395.          The LZW4W library is written in assembly language.  Any  Microsoft
  396.          or  compatible assembler will assemble it. The decision to program
  397.          LZW4W in assembler was made in order to get the  absolute  maximum
  398.          performance  possible.   Although  optimized C is very good, it is
  399.          still bigger and  slower  than  hand  optimized  assembler.  Also,
  400.          assembler  generates  object files which do not contain references
  401.          to the C runtime environment.  This results in a library  that  is
  402.          callable from any code created by any Windows capable compiler.
  403.  
  404.          Internal table space varies with the number  of  code  bits  used.
  405.          Using  a maximum of 12 bits per code (see the InitLZW() function),
  406.          25105 bytes are allocated for table space.  This  value  jumps  to
  407.          45145  bytes  when  using  13  bytes and 90205 bytes when using 14
  408.          bits. The best compression is given using 14 bits per code.
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.         LZW4W Users Manual                                     Page 7
  421.          3.0 Example Programs
  422.  
  423.  
  424.          Two example windows programs are provided.  Each  example  program
  425.          should  be  compiled  with  the  provided makefile.  These example
  426.          programs are meant to demonstrate various ways in  which  the  LZW
  427.          compression library can be used.
  428.  
  429.  
  430.          3.1 RUNLZW
  431.  
  432.  
  433.          The   program   RUNLZW  is  provided  as  both  a  standalone  LZW
  434.          compression / expansion program, and as an example of how  to  use
  435.          the  LZW4W  library  to compress a file.
  436.  
  437.          +----------------------------+
  438.          | - |        RUNLZW          |
  439.          +---+------------------------+
  440.          | Exit About Compress Expand |
  441.          +----------------------------+
  442.          |                            |
  443.          |                            |
  444.          |                            |
  445.          |                            |
  446.          |                            |
  447.          |                            |
  448.          |                            |
  449.          +----------------------------+
  450.  
  451.  
  452.          Choosing  "Compress" will pop up a window to ask for the file name
  453.          to compress:
  454.  
  455.  
  456.          +-------------------------+
  457.          | Enter file to compress  |
  458.          |                         |
  459.          |  +-------------------+  |
  460.          |  | ?                 |  |
  461.          |  +-------------------+  |
  462.          |                         |
  463.          |  +------+   +--------+  |
  464.          |  |  OK  |   | CANCEL |  |
  465.          |  +------+   +--------+  |
  466.          +-------------------------+
  467.  
  468.  
  469.          Type in the name of the file that  you  wish  to  compress.   Type
  470.          ENTER  or  push  the OK button when done. If you change your mind,
  471.          you can always push the CANCEL button.
  472.  
  473.          Choosing "Expand" works in a manner similiar to  COMPRESS,  except
  474.          that  you  are  prompted  for  the  filename  of a file previously
  475.          compressed with LZW4W.
  476.  
  477.          Files created with LZW4W are compatible with  those  created  with
  478.          LZW4C (DOS/C) and LZW4P (DOS/Pascal).
  479.  
  480.         LZW4W Users Manual                                     Page 8
  481.          3.2 ARCHIVE
  482.  
  483.  
  484.          The program ARCHIVE is used to:
  485.  
  486.            1. Create a (compressed) archive file.
  487.            2. Expand an archive file (extract all files).
  488.            3. List the files in an archive file.
  489.            4. Extract a given file from an archive.
  490.  
  491.  
  492.          +----------------------------+
  493.          | - |       ARCHIVE          |
  494.          +---+------------------------+
  495.          | Exit About Archive...      |
  496.          +----------------------------+
  497.          |                            |
  498.          |                            |
  499.          |                            |
  500.          |                            |
  501.          |                            |
  502.          |                            |
  503.          |                            |
  504.          +----------------------------+
  505.  
  506.  
  507.          Choosing "Archive..." result in  the  Archive  menu  being  pulled
  508.          down:
  509.  
  510.  
  511.          +----------------------------+
  512.          | - |       ARCHIVE          |
  513.          +---+------------------------+
  514.          | Exit About Archive...      |
  515.          +------------+----------+----+
  516.          |            | Compress |    |
  517.          |            | Expand   |    |
  518.          |            | List     |    |
  519.          |            | Extract  |    |
  520.          |            +----------+    |
  521.          |                            |
  522.          |                            |
  523.          +----------------------------+
  524.  
  525.  
  526.          Choosing "Compress" will result in a popup window to  request  the
  527.          file  name  of the archive file and the file specification for the
  528.          list of files to archive (compress). For example, to  archive  all
  529.          file  ending  with  ".C"  into  the  file CFILES.ARF, respond with
  530.          "CFILES.ARF" when asked for the archive filename, and  "*.C"  when
  531.          asked for the files to compress.
  532.  
  533.          The  remaining archive entries work in a similiar manner. They all
  534.          use the same style of popup window to  get  information  from  the
  535.          user as described in the above section on RUNLZW.
  536.  
  537.          Files created with LZW4W are compatible with  those  created  with
  538.          LZW4C (DOS/C) and LZW4P (DOS/Pascal).
  539.  
  540.         LZW4W Users Manual                                     Page 9
  541.          4.0 Reader & Writer Functions
  542.  
  543.  
  544.          Both  the  compression and expansion routines in the LZW4W library
  545.          use Reader and Writer functions supplied by  the  library  caller.
  546.          They are provided as a means of giving the caller complete control
  547.          over  the  source  and  destination  of  the  data  stream  during
  548.          compression and expansion.
  549.  
  550.          A reader function is not limited to reading from disk. It may read
  551.          from  any  data source as long as it returns a -1 when there is no
  552.          more data to be read. Similiarly, a writer function may  write  to
  553.          any data sink.
  554.  
  555.          A  simple  (excuse the 1 byte buffers!) example of suitable reader
  556.          and writer functions which can be  used  to  compress  and  expand
  557.          files on disk are as follows:
  558.  
  559.              int Reader(void)
  560.              {int Code;
  561.               char Byte;
  562.               Code = _lread(ReadHandle,&Byte,1);
  563.               if(Code==1) return( Byte );
  564.               else return(Code);
  565.              }
  566.  
  567.              int Writer(char Byte)
  568.              {int Code;
  569.               Code = _lwrite(WriteHandle,&Byte,1);
  570.               return(Code);
  571.              }
  572.  
  573.          The Windows file API functions should be used rather than file I/O
  574.          functions in the C runtime library:
  575.  
  576.               _lopen    -- To open an existing file.
  577.               _lcreat   -- To open a new file.
  578.               _lclose   -- To close a file.
  579.               _lread    -- To read a buffer.
  580.               _lwrite   -- To write a buffer.
  581.  
  582.          Alternatively, OpenFile can be use instead of _lopen and _lcreat.
  583.  
  584.               OpenFile  -- To open a file (existing or new).
  585.  
  586.          Note that the Reader returns a -1 for an end  of  data  condition.
  587.          Data is returned as an integer with the high byte set to 0.  Thus,
  588.          the  only  integers  can  can  be  returned  by  the Reader are -1
  589.          (0xffff) and 0 (0x0000) to 255 (0x00ff).
  590.  
  591.          If you remove data from a character buffer, be sure  to  zero  out
  592.          the  high  order byte (AND with 0x00ff) unless you are returning a
  593.          -1 (EOF).  For an example,  examine  the  code  for  the  Reader()
  594.          function in RW_IO.C.
  595.  
  596.  
  597.  
  598.  
  599.  
  600.         LZW4W Users Manual                                     Page 10
  601.          5.0 Library Functions
  602.  
  603.  
  604.          There are four functions in the LZW4W library as follows:
  605.  
  606.                        InitLZW  -- Initialize LZW library.
  607.                        TermLZW  -- Terminate LZW library.
  608.                        Compress -- Compress
  609.                        Expand   -- Expand (un-compress)
  610.  
  611.  
  612.          5.1 InitLZW
  613.  
  614.  
  615.          Function:     Initialize library
  616.  
  617.          Prototype:    int InitLZW(int BitCode)
  618.                        /* BitCode = maximum bits per code */
  619.  
  620.          Description:  The  InitLZW  function  is  used  to initialize  the
  621.                        library.
  622.  
  623.                        The argument <BitCode> is the maximum number of bits
  624.                        used  per  code  in  the  compression process. Legal
  625.                        values are 12, 13, and  14  (the  preferred  value).
  626.                        Smaller values will use less memory but not compress
  627.                        as tightly.
  628.  
  629.          Returns:      -2 : (CANNOT_ALLOCATE) -- if unable to allocate.
  630.                        -5 : (BAD_BITCODE) -- BitCode not 12, 13, or 14.
  631.                         0 : (AOK) -- no error.
  632.  
  633.          Example:      /* initialize LZW4W */
  634.                        InitLZW(14);
  635.  
  636.  
  637.          5.2 TermLZW
  638.  
  639.  
  640.          Function:     Terminate library
  641.  
  642.          Prototype:    int TermLZW(void)
  643.  
  644.          Description:  The  TermLZW  function  is  used  to  terminate  the
  645.                        library  after  all  processing is  done. It must be
  646.                        called in order to free the table space allocated by
  647.                        InitLZW().
  648.  
  649.          Returns:      0 : (AOK) -- no error.
  650.  
  651.          Example:      /* terminate LZW4W */
  652.  
  653.                        TermLZW();
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.         LZW4W Users Manual                                     Page 11
  661.          5.3 Compress
  662.  
  663.  
  664.          Function:     Compresses a data set.
  665.  
  666.          Prototype:    int Compress(int (far pascal *Reader)(void),
  667.                                     int (far pascal *Writer)(char))
  668.                        /* args are pointers to Reader() & Writer() */
  669.  
  670.          Description:  The  Compress  function  is used to compress  a data
  671.                        set.  The Reader function always  returns  the  next
  672.                        input  byte.  The  Writer function consumes the next
  673.                        output byte. Refer to the section  on  Reader/Writer
  674.                        I/O.
  675.  
  676.          Returns:      -4 : (NOT_READY) -- Didn't call InitLZW() first.
  677.                         0 : (AOK) -- No error.
  678.  
  679.          Example:      /* compress a file */
  680.                        int FileInp;
  681.                        int FileOut;
  682.  
  683.                        FileInp = FileOpen("LZW4W.DOC",OF_READ);
  684.                        FileOut = FileOpen("LZW4W.LZW",OF_CREATE);
  685.                        Compress(Reader,Writer);
  686.  
  687.  
  688.          5.4 Expand
  689.  
  690.  
  691.          Function:     Expands a file.
  692.  
  693.          Prototype:    int Expand(int (far pascal *Reader)(void),
  694.                                   int (far pascal *Writer)(char))
  695.                        /* args are pointers to Reader() & Writer() */
  696.  
  697.          Description:  The  Expand  function is used to de-compress  a file
  698.                        previously compressed with  the  Compress  function.
  699.                        The  Reader  function  always returns the next input
  700.                        byte.  The Writer function consumes the next  output
  701.                        byte.  Refer  to  the  section on Reader/Writer I/O.
  702.  
  703.          Returns:      -1 : (EXPANSION_ERROR)  -- File not compressed by
  704.                              the compress function.
  705.                         0 : (AOK) -- No error.
  706.  
  707.          Example:      /*  de-compress a file */
  708.                        int FileInp;
  709.                        int FileOut;
  710.  
  711.                        FileInp = FileOpen("LZW4W.LZW",OF_READ);
  712.                        FileOut = FileOpen("LZW4W.DOC",OF_CREATE);
  713.                        Expand(Reader,Writer);
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.         LZW4W Users Manual                                     Page 12
  721.          6.0 Error Codes
  722.  
  723.  
  724.          Be  sure and check the return codes from each LZW4W function call.
  725.          There are only 5 error codes returned by the LZW4W  library  other
  726.          than  0  (no  error). All error codes are negative numbers.  Their
  727.          numerical values are in the  LZW4W.H  file.  Each  error  code  is
  728.          returned by a library function as follows:
  729.  
  730.          ****************************************************************
  731.          *    Error Name    *  IntLZW  *  TermLZW * Compress *  Expand  *
  732.          ****************************************************************
  733.          * EXPANSION_ERROR  *    No    *    No    *    No    *    Yes   *
  734.          * CANNOT_ALLOCATE  *    Yes   *    No    *    No    *    No    *
  735.          * INTERNAL_ERROR   *    Yes   *    No    *    No    *    No    *
  736.          * NOT_READY        *    No    *    No    *    Yes   *    Yes   *
  737.          * BAD_BITCODE      *    Yes   *    No    *    No    *    No    *
  738.          ****************************************************************
  739.  
  740.  
  741.          6.1 EXPANSION_ERROR
  742.  
  743.          An EXPANSION_ERROR error is returned only by the Expand()  library
  744.          function. It is caused by attempting to expand a file that was not
  745.          compressed   by  the  Compress()  function.  Note,  however,  that
  746.          Expand() may expand a file that was not compressed  by  Compress()
  747.          without returning an EXPANSION error.
  748.  
  749.          6.2 CANNOT_ALLOCATE
  750.  
  751.          A  CANNOT_ALLOCATE error is returned only by the InitLZW() library
  752.          function.  It is  caused  when  the  Alloc()  function  passed  to
  753.          InitLZW()  returns  a  NULL  pointer,  indicating  that  it cannot
  754.          allocate sufficient memory.
  755.  
  756.          6.3 INTERNAL_ERROR
  757.  
  758.          An INTERNAL_ERROR error is returned only by the InitLZW()  library
  759.          function  and  only  in  the  shareware  version.  It is caused by
  760.          modification of the Shareware screen. You should  never  get  this
  761.          error.
  762.  
  763.          6.4 NOT_READY
  764.  
  765.          A NOT_READY error is  returned  by  the  Compress()  and  Expand()
  766.          library  functions. It is caused by calling Compress() or Expand()
  767.          without first calling InitLZW().
  768.  
  769.          6.5 BAD_BITCODE
  770.  
  771.          A  BAD_BITCODE  error  is returned from InitLZW() when specifing a
  772.          BitCode of other than 12, 13, or 14.
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.         LZW4W Users Manual                                     Page 13
  781.          7.0 Legal Issues
  782.  
  783.          7.1 Registration
  784.  
  785.          If you wish to register the LZW4W Library, please send $45 plus $3
  786.          S&H ($6 outside of North America) to:
  787.  
  788.                   MarshallSoft Computing, Inc.
  789.                   Post Office Box  4543
  790.                   Huntsville AL 35815
  791.  
  792.          We accept  American  Express  (account  number,  expiration  date,
  793.          exact  name  on  your  card,  and  complete  AmEx  billing address
  794.          required), checks in US dollars  drawn  on  a  US  bank,  purchase
  795.          orders  (POs)  from  recognized  US schools and companies listed in
  796.          Dun &  Bradstreet,  and  COD  (street  address  and  phone  number
  797.          required)  within  the USA (plus a $3 COD charge).  Print the file
  798.          PCL4C.INV if an invoice  is  needed.
  799.  
  800.          You  can  also  order LZW4W from The Public Software Library (PSL)
  801.          with your MC, Visa, AmEx, or Discover card by calling 800-242-4PSL
  802.          (from overseas: 713-524-6394) or by  FAX  at  713-524-6398  or  by
  803.          CompuServe  at  [71355,470].  THESE NUMBERS ARE FOR ORDERING ONLY.
  804.          The product number for LZW4W is 11482.
  805.  
  806.          If  you  wish  to  update from an older version of LZW4W, send $15
  807.          plus  $3  S&H  ($6 outside  of  North  America).  Updates  must be
  808.          ordered directly from MarshallSoft Computing.
  809.  
  810.          The registered package includes:
  811.  
  812.          o  The LZW4W library without the shareware screen.
  813.          o  Assembler source code for the library.
  814.          o  Laser printed Users Manual.
  815.          o  Telephone / FAX / BBS  support for one year.
  816.  
  817.          Print  the  file LZW4W.INV if an invoice is needed. The registered
  818.          user will receive the latest version of LZW4W shipped by  two  day
  819.          priority  mail  (packet  airmail  overseas).   A 5.25" diskette is
  820.          provided unless a 3.5" diskette is requested.
  821.  
  822.  
  823.          6.2 Referral Program
  824.  
  825.  
  826.          The  registered  user  will  receive  a $5 certificate towards any
  827.          MarshallSoft  Computing  product  by  referring  a  new   customer
  828.          (someone  who  has  never registered anything with us) paying full
  829.          price ($45).  The new customer must identify you at the  time  the
  830.          order is placed.  You will be mailed a $5 certificate when the new
  831.          registration is paid.
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.         LZW4W Users Manual                                     Page 14
  841.          7.2 License
  842.  
  843.  
  844.          MarshallSoft  Computing,  Inc. grants the registered user of LZW4W
  845.          the right to use  the  LZW4W  library  (in  object  form)  in  the
  846.          development   of  any  software  product  without  any  royalties.
  847.          However,  the  source  code  for  the   library   (LZW4W.ASM)   is
  848.          copyrighted  by  MarshallSoft  Computing  Inc.,  and  may  not  be
  849.          released in whole or in part.
  850.  
  851.  
  852.          7.3 Warranty
  853.  
  854.  
  855.          MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING  TO
  856.          THIS  SOFTWARE,  WHETHER  EXPRESSED  OR IMPLIED, INCLUDING BUT NOT
  857.          LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY  AND  FITNESS
  858.          FOR  A  PARTICULAR  PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY
  859.          AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING,  INC.
  860.          NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION,
  861.          OR  DELIVERY  OF  THIS  SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT,
  862.  
  863.          CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT  OF  THE  USE  OR
  864.          INABILITY  TO  USE  SUCH  SOFTWARE EVEN IF MARSHALLSOFT COMPUTING,
  865.          INC.  HAS BEEN ADVISED OF  THE  POSSIBILITY  OF  SUCH  DAMAGES  OR
  866.          CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY
  867.          FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO
  868.          USE  THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON
  869.          USING  THE  SOFTWARE  BEARS  ALL  RISK  AS  TO  THE  QUALITY   AND
  870.          PERFORMANCE OF THE SOFTWARE.
  871.  
  872.          Some  states  do not allow the exclusion of the limit of liability
  873.          for consequential or incidental damages, so the  above  limitation
  874.          may not apply to you.
  875.  
  876.          This  agreement  shall  be  governed  by  the laws of the State of
  877.          Alabama and shall inure to the benefit of Marshallsoft  Computing,
  878.          Inc.   and  any successors, administrators, heirs and assigns. Any
  879.          action or proceeding brought by either  party  against  the  other
  880.          arising  out of or related to this agreement shall be brought only
  881.          in a STATE or FEDERAL COURT of competent jurisdiction  located  in
  882.          Madison County, Alabama. The parties hereby consent to in personam
  883.          jurisdiction of said courts.
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.         LZW4W Users Manual                                     Page 15
  901.          8.0 Revision History
  902.  
  903.  
  904.          Version 1.0 -- July 8, 1994
  905.  
  906.          o   Original  release.  Based on release 1.4 of the equivalent DOS
  907.          based products LZW4C and LZW4P.
  908.  
  909.  
  910.          9.0 Other MarshallSoft Computing Products for Windows
  911.  
  912.  
  913.          Shareware  versions  of  all  MarshallSoft  Computing products are
  914.          available on our user support BBS at 205-880-9748  (1200  to  9600
  915.          baud, 8N1).
  916.  
  917.  
  918.          9.1 The Personal Communications Library for Windows
  919.  
  920.  
  921.          The Personal Communications Library  for  Windows  (PCL4W)  is  an
  922.          asynchronous   comm   library  for  Windows  developers.  Supports
  923.          COM1-COM4 to 115200 baud, 4 ports concurrently, all memory models,
  924.          DigiBoard PC/8, INS16550, interrupt driven, RTS/CTS flow  control.
  925.          Requires  Microsoft  C 7.0 or Borland C 3.1 & 4.0. Includes simple
  926.          windows terminal emulator  program.  Distributed  by  MarshallSoft
  927.          Computing, Inc. as SHAREWARE (V1.0, $95). <ASP>
  928.  
  929.          o 36 communications and support functions.
  930.          o Supports the high performance INS16550 UART.
  931.          o Supports hardware (RTS/CTS) flow control.
  932.          o Interrupt driven transmitter (optionally) & receiver.
  933.          o Supports 300 baud to 115,200 baud.
  934.          o Supports COM1 through COM16.
  935.          o Adjustable receive queues from 8 bytes to 32 KB.
  936.          o Control-BREAK error exit.
  937.          o 17 communications error conditions trapped.
  938.          o Support the PC/4 and PC/8 DigiBoards.
  939.          o Supports the BB1004, BB1008, and BB2016 BOCA boards.
  940.          o Allows 4 - 16 ports to run concurrently.
  941.          o Complete modem control & status.
  942.          o Written in assembly language for small size & high speed.
  943.          o Terminal program featuring XMODEM, YMODEM, & YMODEM-G.
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.         LZW4W Users Manual                                     Page 16
  961.